gh-150319: Replace all documentation which says "See PEP 585"#150325
gh-150319: Replace all documentation which says "See PEP 585"#150325sirosen wants to merge 8 commits into
Conversation
The following classes in the stdlib get simple updates: - array.array - asyncio.Future - asyncio.Task - collections.defaultdict - collections.deque - contextvars.ContextVar - contextvars.Token - ctypes.Array - os.DirEntry - re.Match - re.Pattern - string.templatelib.Interpolation - string.templatelib.Template - types.MappingProxyType - queue.SimpleQueue - weakref.ref The following classes are documented publicly as functions, and are therefore updated internally (`__class_getitem__.__doc__`) but not in the public docs: - functools.partial - itertools.chain The following builtin types have updates to `__class_getitem__.__doc__` but not to any documentation pages: - BaseExceptionGroup - coroutines (from generators) - dict - enumerate - frozendict - frozenset - generators (and async generators) - list - memoryview - set - slice - tuple Special cases: - union objects are now documented as "supporting class-level []", rather than anything to do with generics. - Templates might be generic over a single type (union, in theory) or over a TypeVarTuple. As this is not currently fully settled, it is marked with a comment and a mild hint that it is a single type is used (namely, "type" is singular rather than "types", plural)
sirosen
requested review from
1st1,
AA-Turner,
JelleZijlstra,
ZeroIntensity,
asvetlov,
iritkatriel,
kumaraditya303,
lysnikolaou,
markshannon,
methane,
rhettinger and
willingc
as code owners
Documentation build overview
25 files changed ·
|
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
|
Also, any reason you didn't add any wording to the documentation for the builtin generic classes (list etc.)? |
And expand the text for tuples. Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
|
I pushed the corrections in a co-authored commit, along with
|
Missed this question yesterday, sorry! I thought they would grow scope here too much. I'm treating the question as a nudge and will take a look at adding all of them. |
|
I have still omitted two things because I wasn't quite sure where to document them:
I'm also not 100% confident that a few of these, like |
Fix `generic` links which weren't marked as `:ref:`.
Co-authored-by: Jelle Zijlstra <906600+JelleZijlstra@users.noreply.github.com>
AlexWaygood
left a comment
AlexWaygood
left a comment
There was a problem hiding this comment.
This is excellent. We should have done this a long time ago. Thank you!!
I left some comments below. Mostly I'm trying to make sure that we use consistent terminology in the added documentation to the terminology used in the documentation immediately above it. For example, the documentation for list says:
The constructor builds a list whose items are the same and in the same order as iterable's items
so I think we should say that "Lists are generic over the types of their items" rather than that they are generic over the types of their contents
| references to context variables which prevents context variables | ||
| from being properly garbage collected. | ||
|
|
||
| Context Variables are :ref:`generic <generics>` over the type of their value. |
There was a problem hiding this comment.
| Context Variables are :ref:`generic <generics>` over the type of their value. | |
| Context Variables are :ref:`generic <generics>` over the type of | |
| their contained variable. |
There was a problem hiding this comment.
Is "contained variable" best? I would prefer "contained value", since that matches doc for get() and set(), both of which refer to a "value".
Update: I applied a change to make this "contained value"; let me know if it should change further.
|
(Oh, I only reviewed the edits to the |
Yeah, it almost certainly needs to go into the docstrings -- I started my work from those and did the RST afterwards. I think that also explains why it's inconsistent with some of the RST doc. I hadn't thought to double-check for consistent language, which seems obviously desirable to me now! I'll work through the feedback and apply the changes in both places. 👍 |
These are applied at both the originally indicated locations and in the corresponding docstring definitions. Co-authored-by: Alex Waygood <66076021+AlexWaygood@users.noreply.github.com>
3 participants
This is a documentation update touching many modules, eliminating text which says "See PEP 585".
The general phrasing used is "X is generic over Y", and this is kept consistent as much as possible.
We can use different phrasing; the goal here is to be consistent in whatever we choose.
For types visible in the stdlib, documentation is also lifted up into class-level docs.
For builtins, however, the story for documenting this is in many cases more complex.
Therefore, updates to the doc pages are omitted for now.
The following classes in the stdlib get simple updates:
The following classes are documented publicly as functions, and are therefore updated internally (
__class_getitem__.__doc__) but not in the public docs:The following builtin types have updates to
__class_getitem__.__doc__but not to any documentation pages:Special cases:
union objects are now documented as "supporting class-level []", rather than anything to do with generics.
Templates might be generic over a single type (union, in theory) or over a TypeVarTuple. As this is not currently fully settled, it is marked with a comment and a mild hint that it is a single type is used
(namely, "type" is singular rather than "types", plural)
Additional issues resolved:
memoryviewis generic in #149488